home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
C/C++ Interactive Reference Guide
/
C-C++ Interactive Reference Guide.iso
/
c_ref
/
csource4
/
272_01
/
smlibdl.doc
< prev
next >
Wrap
Text File
|
1987-08-17
|
27KB
|
991 lines
==========================
= STEVE'S LIBRARY =
= for Datalight =
= - by - =
= Steven E. Margison =
==========================
Functions and Documentation Copyright 1986 & 1987
by Steven E. Margison -- All Rights Reserved
ISBN 0-944267-06-8
--------- TABLE OF CONTENTS ---------
Introduction ................................. 1
The Documentation ............................ 1
Installation ................................. 2
Linking ...................................... 3
Interrupt Handler Functions .................. 4
Utilities ..... .............................. 5
On Buffering STDOUT .......................... 10
Shareware .................................... 11
Warranty ..................................... 12
Registration Form ............................ --
Steve's Function Library for Datalight C
I. INTRODUCTION
The heart of the C language is its library. Each
compiler has its own library of functions, which is complete
only to the degree that the compiler author wishes to make it.
The Datalight C Compiler is an excellent product which has
gotten rave reviews in computer magazines. (I have both Lattice
3.1 and Datalight available to me and I prefer the Datalight by
far.) The greatest criticism which can be leveled at Datalight
is the size of its library. It has all the usual basic
functions, plus some nice unique features. But it still can use
some help. Enter Steve's Library! At over 100 functions my
library greatly enhances program development with Datalight C.
II. THE DOCUMENTATION
The documentation for the library is contained in a
number of .DOC files, which describe each function. When
printed, these pages may be placed in a standard three-ring
binder. A utility program, PMAN.COM is provided to generate the
entire set of documents. PMAN requires the file LISTALL, which
may be edited to eliminate printing of certain files if desired.
(PMAN is copyrighted, but placed in the public domain.)
To print the DOC files, you must be in a directory (or
on a floppy) containing PMAN, LISTALL, and all the DOC files.
Just type "PMAN" at your system prompt and the files will be
printed to PRN:.
Steve's C Library for Datalight Page 1
III. INSTALLATION
Steve's Library is distributed as four library files for each
type of memory model. (Only the full registration with source
has all four libraries.) The filenames are:
SMDLS.LIB Small Memory Model
SMDLD.LIB Large Data Model
SMDLP.LIB Large Code Model
SMDLL.LIB Large Code and Data Model
For the remainder of this manual the libraries will be referred
to as SMDLx.LIB.
A typical hard disk installation of Datalight will consist of a
directory named \DC in which will be found the compiler,
Datalight libraries, and Datalight header files. SMDLx.LIB
should be copied into this directory as well, or into whatever
directory the Datalight libraries have been installed.
Steve's Library also includes several header files which list
"define"s for many useful items. These header files are also
required to re-compile the source for the libraries. The header
files should be copied into the \DC directory, or in whatever
other directory contains stdio.h, dos.h, and the other header
files. If you have purchased the source files and wish to have
them on hard disk, make a new subdirectory under the \DC main
directory called SM (C:\DC\SM) and copy all source files to that
directory.
Steve's C Library for Datalight Page 2
IV. LINKING
The SMDLx.LIB library must be linked with any other
libraries whenever a function is used in your program. Some
programs may not use SMDLx.LIB functions, and therefore the
linking of the library may be eliminated to save time. The
Datalight driver (DLC) command line would look like this:
DLC MYPROGRAM \DC\SMDLS.LIB
Naturally, if your directory structure is not the standard,
specify the paths as needed. In addition, if you have other
third party libraries, be sure to include them after SMDLx.LIB.
Steve's C Library for Datalight Page 3
V. INTERRUPT HANDLER FUNCTIONS
A special feature of Steve's Library is the various
interrupt handler functions. These are:
ticker
ctlbrk
criterr
These functions provide the programmer with the ability to
install a special routine to intercept one of the DOS
interrupts. ctlbrk() installs a user-defined routine to be
executed whenever a control-break is typed on the keyboard.
criterr() traps the DOS critical error handler (the one that
says Abort, Retry, etc.) and allows the programmer to substitute
his own handler. ticker() is not really a user definable
handler, but a pre-built handler which allows the user to
perform operations relative to the system's clock. A special
variable may be loaded with a value and then tested at
intervals. When the variable has hit zero, a specific amount of
time has passed. The variable counts 18.2 times per second, and
is installed on INT 1CH.
The usage of these interrupt handlers is slightly complex and
interactive. For example, if you use ticker() you must use
ctlbrk() and you may have to use criterr(). It has been said
that a picture is worth a thousand words. Well, to me, a source
file is worth a whole chapter of tutorial. Therefore, refer to
TESTINTS.C, which is supplied with all distributions of Steve's
Library , to see a heavily commented source code file which uses
these interrupts. This program may be compiled and run to watch
the result.
Steve's C Library for Datalight Page 4
VI. THE UTILITIES
Beginning with Release 1.20 of my library, I am shipping
the source code for several utiltiies I have written. Nothing
earth shaking here, just some convenient programs to make life a
little easier. All the programs use several functions from
Steve's Library, and can serve as an example of proper usage.
Here is a short description of each utility:
INPATH
This utility searches for an EXECUTABLE program in the
current path. Typing INPATH at the DOS prompt will display the
version number and a short usage message. To use, type:
inpath <filename>
where filename is the basename portion of the executable file to
find. Note that an extension can be specified, but it is
ignored. INPATH will first look for the file in the current
directory, and then look in the PATH environment variable (if it
is present) in the order specified. For each directory, INPATH
first tries to locate a .COM file, then a .EXE file, then a .BAT
file, since that is the order in which DOS searches for files.
On the first match, INPATH reports the directory and full
filename of the program and then exits. If none are found, that
fact is reported.
INPATH demonstrates the use of newext() and error().
TC
This is a quick Text Compare program to compare two
ASCII files. Typing TC at the DOS prompt will display the
version number and a short usage message. To use, type:
tc file1 file2
where file1 and file2 are the two files to compare. If the
files are identical, no more messages will appear. Otherwise,
the program will report any lines which are different with the
filename, line number, and a printout of the actual line. If
one file ends before the other, the program reports which file
terminated first.
TC demonstrates the use of error() and cant().
Steve's C Library for Datalight Page 5
WC
WC counts words, lines, characters, and checksums one or
more files. Typing WC at the DOS prompt will display the
version number and a short usage message. To use, type:
wc filename [-wcls]
where filename is the name of the file to act upon. With no
options, the program will report words, characters, lines, and a
checksum, which is a simple binary addition of all character
values. No, it ain't a CRC, but it is a quick check to see if
it the same as another file under the same name. The options
[wcls] tell the program to report ONLY the items specified:
-w report only words
-l report only lines
-c report only characters
-s report only checksum
Note that giving all options is the same as giving no options.
Since words, lines, and characters are meaningless in a non-text
file, the program examines the filename extension to determine
if the file is a binary or text file. This isn't a perfect
method, but it is good enough. If the file extension is .COM,
.EXE, .OBJ, .REL, .PFS, .LIB, or .BIN, then only the checksum is
reported, overriding all other options. The program supports
wildcards in the filename, as well as drives and directories.
WC demonstrates the use of exttyp(), cant(), and the wildcard
_main object file by Datalight.
Steve's C Library for Datalight Page 6
OKISET
This program is used to set the printing options
available on an Okidata ML84 (with IBM Plug 'n' Play), or most
other IBM compatible printers. It may be easily customized for
other printers. This is a menu driven program requiring no
options. Just execute it and follow the directions!
F1 PITCH
Use the SPACE key to toggle between normal (10 cpi)
and condensed (17.5 cpi) pitch. Press RETURN to make
the selection.
F2 STYLE Use the SPACE key to toggle between draft
and letter quality style, and press RETURN to select.
F3 LQ SPACING Enter 1 or 2 digits in the range
00-11 to select letter quality spacing. ESCape will
abort this entry, BACKSPACE will allow you to start
the entry over, and RETURN selects the entered value.
This selection assumes letter quality mode, and forces
the style to letter quality, and the pitch to 10 cpi.
F4 LINES PER PAGE Enter 1 or 2 digits in the range
01-99 to set the page length in lines per page.
ESCape, BACKSPACE, and RETURN operate as for F3.
F5 LINE SPACING Use SPACE key to toggle between 6
LPI and 8 LPI spacing, and press RETURN to select.
F7 OUTPUT CHANNEL Use SPACE key to step through
output channels PRN, LPT1, and LPT2. Press RETURN to
select.
F9 NORMAL OPTIONS This key sets all other options
as follows: pitch > 10 CPI style > Draft
lines > 66 space > 6 LPI output > PRN
F10 SEND CONTROL CODES and EXIT No control codes
are sent until this key is pressed. Only control
codes which have been selected are sent. If the pitch
selection remains blank in the menu, for example, the
pitch control code will not be sent. This allows only
some options to be changed without disturbing the
existing printer configuration.
Letter quality and condensed modes cannot be mixed on the
printer. Therefore, if a conflicting selection is made, the
last entry will force correct options.
OKISET will present various beeps for invalid keystrokes, and
warning messages where appropriate.
Steve's C Library for Datalight Page 7
OKISET will demonstrate cls(), mkbox(), d_say(), getkey(),
d_pos(), and show how to manage a non-scrolling program.
Programming idea: re-write this program using the direct video
access routines.
GTOD
This utility will report the current system time and
date in a variety of formats. GTOD may be invoked with or
without options. Options may be preceded by dash, fraction bar,
or nothing at all.
gtod <options>
-d report only date
-t report only time
-e report date in European format (DD/MM/YY)
-s report seconds, if time reporting enabled
-r reverse reporting order, with time first and date second
-l spell out month in long format
-n if option -l, then add name of weekday
-m report time in 24 hour (military) format
-v report version number
-? usage message and exit
no options defaults to -dt
Output may be redirected to a file or another device, except for
error messages.
GTOD demonstrates the rather obscure Datalight system clock
interface, as well as error(), monthis(), wkdayname(), i_dstr(),
and weekday(). Program idea: allow calculation for other time
zones.
Steve's C Library for Datalight Page 8
DUMP
(Oh! No! Not aNOTHer file dump utility!) Well, yes,
and I apologize all to h*ll. However, this one started out as a
utility supplied with the Datalight compiler, which I hacked to
death. First, it will be in **COLOR** if it senses a CGA card
installed, and will use blinks and highlights if a mono card is
sensed. Second, it fixes a minor bug or two in Datalight's
version. Third, and here comes the unique part, it will
highlight any selected byte whenever it is found! (Well, at
least I think it's handy.) Fourth, it displays only 20 lines at
a time and waits for a keypress to continue. Invoke the program
as follows:
dump filename <offset> <byte>
where filename is the file to dump, offset is the hex offset
value in which to index into the file before dumping (defaults
is 0000), and byte is the hex value to highlight (default is no
highlight). The parameters MUST be in the order specified, and
the offset must be supplied (as a place holder) if the byte
option is desired.
DUMP demonstrates the use of getkey(), stuff(), error(), plus
many of the disp* functions of this library and Datalight, and
the use of color attributes. Programming idea: there are
several ways to increase the speed of the program. I haven't
implemented them so that you can have the fun(!!) of doing it.
Hint: the overhead in printf() is horrendous.
Steve's C Library for Datalight Page 9
VII. ON BUFFERING STDOUT
Beginning with Version 3.* of Datalight, the authors
have decided to buffer the output to stdout. Well, this ain't
quite right, thinks me. The result is that any data sent to
stdout (usually the console) is held up until (a) the buffer is
full, (b) a newline character is sent, or (c) fflush(stdout) is
called. This is a royal pain, but it can be fixed. The module
IOB.C can be modified to set _IONBF in the stdout definition. I
have included a source module, IOBNBF.C, with this modification.
It can be renamed to IOB.C and recompiled if desired. Use an
object module librarian program to replace the module in the
Datalight libraries. Or, simply leave it as an OBJ file and
link it into your programs. Since the linker will see it before
the same module in the library, it will then take precedence.
This may actually be better, since it gives you the ability to
use either buffered or unbuffered stdout output. All of the
utilities I supply with my library are designed to use
unbuffered output.
Steve's C Library for Datalight Page 10
VIII. SHAREWARE
ShareWare is "try-before-you-buy" software, reasonably
priced and user-supported. This simply means that you can get
ShareWare software for free from anyone who has a copy, or often
from bulletin board systems. If you use and like the program,
then the author asks that you register (purchase) the program
for a stated fee. By registering you will often also receive
notice of available upgrades or supplemental programs. Payment
under shareware is on the "honor system", but if the program is
useful and the price is right, then please play by the rules and
purchase the program. Also, keep in mind that the purchase of a
program from a public domain distributor or payment to an online
service (such as CompuServe) does NOT constitute registration of
the program since the producer of the program does not receive
one penny of that payment.
"Steve's Library" is shareware. If you use it, please
register your copy on the registration form enclosed at the end
of this manual. For a slightly higher charge, you may elect to
obtain the source code for all functions, and the D, P, L
libraries. Please note that the extra libraries and the source
code are NOT SHAREWARE, and should not be distributed. Only the
documentation, utilities, header files, and Small model library
may be passed on under the shareware concept.
Online help is available through CompuServe
(74435,1042), or GEnie mail (S.MARGISON) to registered users
ONLY. Help is also available by mail. I will try to answer all
letters within 48 hours. Non-registered users must include a
SASE for a reply. The degree of help available to
non-registered users is purely discretionary. No phone calls,
please.
"Steve's Library" may be used in a commercial
environment, with no royalties required if functions are
included in a program for sale. However, the library, source
code, and all related documentation may not be sold under any
circumstances without my prior approval. Software library
services and Users Groups may charge a nominal fee for copying
and distributing those files which are shareware. Please
contact me for a complimentary copy to insure that you are
offering the most recent and complete release. The source code
may NOT be offered for sale or trade by other than myself.
"Steve's Library" may not be included or "bundled" with any
other software without prior permission.
"Steve's Library" and its documentation may not be
transferred nor exchanged in any modified form. I cannot be
expected to help others use these functions if they are not the
same as distributed. Under no circumstances may the copyright
notices be altered or removed from the functions or
documentation.
Steve's C Library for Datalight Page 11
IX. WARRANTY
Oh, this shouldn't be necessary among friends and
gentlemen, but it's really the lawyers who run the world and
they say we gotta do this:
** Steve's Library functions and all documentation are
copyright 1986, 1987 by Steven E. Margison.
** These functions and documentation are provided "as
is" without warranty of any kind, either expressed or
implied, including but not limited to the implied
warranties of merchantability and fitness for a
particular purpose.
** The user of these functions and documentation agree
to hold the author and/or distributor(s) of this
material harmless for any direct or consequential
damages resulting from its use. In other words,
"you're on your own!"
** IBM is a registered trademark of International
Business Machines Corporation.
** MS-DOS is a trademark of MicroSoft Corporation.
** Datalight C is a registered trademark of Datalight,
Inc.
Steve's C Library for Datalight Page 12
=======================================================================
SOFTWARE REGISTRATION FORM AND ORDER
=======================================================================
A separate form must be filled out for each product ordered or
registered. This form may be photocopied, printed out, or
edited to include all information and re-printed.
PRODUCT: --------- STEVE'S DATALIGHT LIBRARY VERSION 1.30 --------------
QUANTITY: Amount:
_____ Standard registration $10.00 ea $______
_____ Registration with Source code $25.00 ea $______
Shipping outside U.S. or Canada $ 3.00
TOTAL DUE $______
Payment must be made in U.S. Funds
Source code is NOT SHAREWARE and is not to be transferred to other
users. Only the DOC files, header files, utilities,
and S library are released into shareware.
Corporations: Write with your requirements for a quote on
multiple copies or site licensing.
If you already have this library, where was it obtained?
[ ]CompuServe [ ]Friend [ ]Employer [ ]BBS:__________________
Version_____ Serial No._________
Payment is by check[ ] or money order[ ] (Sorry - no COD or charges)
NAME _______________________________________________________
COMPANY ____________________________________________________
ADDRESS ____________________________________________________
CITY _______________________________________________________
STATE___________________________ ZIP _______________________
=======================================================================
Send completed form and payment to:
Steven E. Margison
124 Sixth Street
Downers Grove, IL, 60515
=======================================================================
- do not write below this line -
recd________ sent________ version_______ serial no.__________________